Overview

This page provides instructions for taking an "out-of-the-box" Raspberry Pi and making it "project-ready" by downloading and configuring the operating system to enable features which are most likely to be used by hobbyists. For example, auto-login and auto-launching of python scripts will be enabled, so that projects will auto-start when power is applied. I should provide the disclaimer, that these are the steps that I use, and some of the selections may be different for you. For example, timezone, keyboard layout, etc.

Hardware Tested

These instructions were tested on a Raspberry Pi 1 Model B+. This Raspberry Pi is a 700 MHz 32-bit ARM processor that does not include integrated wireless. For convenience, an Edimax or similar Wi-Fi USB adapter can be used with the RPi 1. Alternatively, a 10/100 Mbit/s wired Ethernet connection can be used. If you have a Raspberry Pi model 2 or 3 (or above), I would recommend using a later version of Raspbian.

Raspberry Pi 1 Model B+	+	(optional) Edimax Wi-Fi USB Adapter or similar

Downloading the Linux image

Before configuring the Raspberry Pi, it is necessary to download the Linux operating system, and install it on the Raspberry Pi. In order to accomplish this step you will need the following:

• A Linux operating system image for the Raspberry Pi
• An SD card with at least 8GB
• An SD card writer
• A program to write the image to the SD card

Normally, I would recommend downloading the latest Raspbian image here: http://www.raspberrypi.org/downloads/raspbian, however, with the rapid pace of hardware and software changes on the Raspberry Pi, it has been my experience that an alternate Raspbian image may not work correctly with the instructions provided on this page. This is not an issue with the instructions, as much as it is that the Raspberry Pi designers are frequently optimizing the design, and this occasionally changes the interactions with the low-level hardware. Most people wouldn't notice these changes, but for a hobbyist trying to use the UART, I2C, SPI, or GPIO interfaces, these changes can be a little frustrating.

Here is a copy of the image that I used while creating these instructions:

• 2013-12-20-wheezy-raspbian.zip
• SHA-1: ADE48C874F8E4B694175DE4C87D7357960961FBF (For the zip archive)
• SHA-1: 50299DFE7AD9C04F180C526807A1218249265E11 (For the image only)

Notice that both here and on the official Raspbian download page, a checksum is provided. It is highly recommended that you verify the downloaded image to ensure that it is not corrupted before using it. To do this, download and run the MD5-SHA_Checksum Utility. Un-select all of the checkboxes except for SHA-1 (this just speeds things up). Copy the SHA-1 checksum provided with the file, and paste it into the "Hash:" text box. Click Browse and navigate to the downloaded file. The calculation of the checksum will begin immediately. When the calculation of the checksum is complete, click on the Verify button. If you you get a pop-up window that says "SHA-1 Hash matched.", then life is good.

Next, the image needs to be loaded onto the SD card. To do this, download and run the win32diskimager. Select the blue folder icon to the right side of the Image File text box to browse for and select the image file to be written. Select the drive letter of the SD card that you want the image written to. IMPORTANT: be very sure that you are selecting the correct drive letter. Once you are absolutely sure, select the Write button. This will begin the writing process. On my computer, writing to an 8GB card takes about 11 minutes.

First-Time Configuration

Place the SD card with the freshly written image into the Raspberry Pi, and apply power. (This assumes that keyboard, mouse, and display are already properly connected) The very first time that power is applied, the Raspberry Pi Software Configuration Tool (raspi-config) will launch automatically. At this point the mouse will not work yet. Use the arrow keys and the tab key to perform the following steps

To manually start the configuration tool in the future, open a terminal window, enter the following, and press enter.

Within the configuration tool, perform the following actions:

• Select 1 Expand Filesystem
• (A pop-up message will be displayed to let you know that the root partition was resized, and that the filesystem will be enlarged upon the next reboot)

• Select 3 Enable Boot to Desktop/Scratch
• Select Desktop Log in as user 'pi' at the graphical desktop

NOTE: If you decide not to use auto-login (not recommended), you'll want to know the following:

• default login: pi
• default password: raspberry
• to start the graphical desktop: startx

• Select 4 Internationalization Options
• Select I1 Change Locale
• Unselect en_GB.UTF-8 UTF-8
• Select en_US.UTF-8 UTF-8
• (spacebar selects/de-selects. Press enter to exit)
• On exit, you may be asked to “Select the default locale for the system environment”. Select en_US.UTF-8

• Select 4 Internationalization Options
• Select I2 Change Timezone
• Select Geographic area = US
• Select Eastern

• Select 4 Internationalization Options
• Select I3 Change Keyboard Layout
• Select Generic 105-key (Intl) PC
• In Keyboard layout select Other
• In Country of Origin... select English (US)
• In Keyboard layout select English (US)
• Key to function as AltGr: Left Logo Key
• Compose key: No compose key
• Use Control+Alt+Backspace to terminate X server?: No

Note: we are intentionally skipping the advanced options until after the Linux image is updated.

Tab to <Finish> and press Enter. In the window that appears, select <Yes> to answer the question of whether to reboot now, and press Enter.

User documentation for raspi-config can be found at: raspi-config documentation

Initial Login

After the reboot in the previous section, the graphical desktop should appear. It's the one with a huge raspberry in the middle of a glaring white background. This is a matter of personal preference, but let's change the background to something more tolerable. Using the mouse, Right-Click on the desktop (for example on the raspberry) and select "Desktop Preferences". In the window that appears, select the color button next to "Background Color:". In the window that appears, enter "#204060" (without the quotes) in the textbox next to Color name:, and select Ok, and Close. Aah, that's better!

For some of the next steps an internet connection is required. If you are connecting with a wired LAN connection, then everything is automatic and you can ignore this section. If you have a wireless connection then there are only a few simple steps to create a connection. Click on the "WiFi Config" icon on the desktop. The wpa_gui window will pop up with the current status tab already selected. Press the Scan button. An empty Scan Results window will pop up. Press Scan again to populate the window. You should see your WiFi SSID (assuming it is configured properly). Double-click on the desired SSID. Fill in the necessary information, for example the PSK for a WPA2 authentication, and press the Add button. Select Close on the Scan results window. The connection should be made automatically. If it isn't press the Connect button.

Update the Linux Image

In order to update the linux image, open a terminal window, and enter

This command downloads the package lists from the repositories and updates them to get information on the newest versions of the packages and their dependencies. It does not change any of the software on the Raspberry Pi. While this is working you should see the http addresses of various repositories, with incrementing progress (to 100%), and finally a message that indicates "Fetched N,NNN kB in XXs (YYY kB/s)", "Reading package lists... Done", and a return to a command prompt. Now enter:

This command will install the newest version of all packages that are currently installed on the Raspberry Pi. This step can take a very long time! So, if you want to go see a movie or take the family out for dinner, now would be a good time.

Hint: For some upgrades you will be asked whether you want to continue, and a [Y/n] option is presented. The capitalized letter represents the default option. For example, in this case, with Y capitalized, if you just press Enter, the interpreted response is Yes. The '-y' option above will automatically answer yes for you.

Second-Time Configuration

Now that everything is up to date, let's configure the advanced options. Start the configuration tool again by opening a terminal window, and entering the following:

Within the Raspberry Pi Software Configuration Tool, perform the following actions:

• Select 8 Advanced Options
• Select A6 SPI
• Would you like the SPI interface to be enabled? Yes
• The SPI interface is enabled. Ok
• Would you like the SPI kernel module to be loaded by default? Yes
• SPI kernel module will now be loaded by default. Ok

• Select 8 Advanced Options
• Select A7 I2C
• Would you like the ARM I2C interface to be enabled? Yes
• The ARM I2C interface will be enabled after a reboot. Ok
• Would you like the I2C kernel module to be loaded by default? Yes
• I2C kernel module will now be loaded by default. Ok

Tab to <Finish> and press Enter. In the window that appears, select <Yes> to answer the question of whether to reboot now, and press Enter.

Enable Low-Level Hardware Control

Next, load some kernel modules to enable the low-level drivers that hobbyists will want for various projects. These are not normally enabled in typical Linux distributions.

Open a terminal window, and enter

Add or ensure the following lines are at the end of the file:

After adding the text, save the file, and exit.

In this image, the spi and i2c modules are not blacklisted, so there is no need to remove any items from the blacklist file: /etc/modprobe.d/raspi-blacklist.conf.

In order to use the serial port, we need to make a few changes. Disable the boot-up and diagnostic output to the serial port. Open a terminal window, and enter

Remove the two options referring to the serial port.

Disable the serial port login prompt. Open a terminal window, and enter

find the following line near the end and delete it or comment it out by putting a # at the start of the line.

Install Python Packages

In order to control the hardware peripherals such as GPIO pins, or communications with UART, SPI, I2C, you will need to have some Python libraries installed. Before continuing however, let's start with bringing everything up to date. Open a command-line window, such as LXTerminal, and type the following:

Using the command-line prompt, install the following Python packages, in this order:

For Python development I like to use Geany, and to auto-launch Python scripts, I use xterm. Install these applications by entering the following:

With the raspbian-wheezy image, the python i2c interface doesn't work without a little additional help. Install the HiPi module by opening a terminal window, and enter:

This will ask if you want to install pre-built modules for your architecture. Answer yes. It will ask whether you want to install the missing packages now. Answer yes. This may take a long time to install completely.

Once installed you can run the HiPi Control GUI with the command below. If the gui window is displayed, then the installation worked.

IMPORTANT: When you open the hipi-control-gui, navigate to the SPI and I2C tabs. If the checkboxes for "kernal modules loaded" are not checked, execute the second-time configuration steps again. On two RPi 1 model B+ boards I received an error "could not insert 'spi_bcm2708': No such device". I don't have a solution for this at this time.

Note: It is necessary to run the control gui using gksudo (graphical sudo) because the HiPi Control GUI needs permissions to access the GPIO pins and device driver settings.

Now that HiPi is installed, you can upgrade it in the future using these commands:

Disable Screen Blanking

As a hobbyist it is very likely that you will want the display to stay on, and not perform the screen blanking of a typical Linux distribution. To make this happen, enter the following:

Add the following lines to the [SeatDefaults] section:

The x11 utils are already loaded in this version of Raspbian. If they weren't you would need to install xset, a lightweight application that controls X settings, by entering the following:

Create a file at ~/.xinitrc by entering the following:

Inside the blank file, enter the following:

Now restart the Raspberry Pi to reload the new settings. Enter the following:

HDMI Display Settings

Normally, the HDMI output is only enabled if a connection is detected at startup. If you are using the Raspberry Pi in a configuration where the display may not be connected at startup, for example where it may run autonomously, but where you may want to be able to later connect an HDMI display to view a running script, the following steps can resolve the situation.

Open a terminal window, and enter

Uncomment the following line:

The remaining HDMI steps are optional

When the HDMI port is forced on and the monitor was not available to negotiate settings at power-on, or in some cases where the display and Pi are powered on at the same time and proper HDMI negotiation isn't occurring, the resolution will default to a value which may be lower than the connected display. These settings are not re-negotiated at each connection, only at power-on. If you know the settings for your display, you can force those settings by also adding the following to the /boot/config.txt file.

Add the following line after the hdmi_force_hotplug=1:

The values shown above are for the SunFounder 10.1 inch LCD Display. Replace these values with your own. The format is hdmi_cvt=<width> <height> <framerate> <aspect> <margins> <interlace> <rb>. The <width> is the width in pixels, and <height> is the height in pixels. <framerate> is the frame rate (a.k.a. refresh rate) in Hz. <aspect> is the aspect ratio, which is a pick list value. The options are: 1=4:3, 2=14:9, 3=16:9, 4=5:4, 5=16:10, and 6=15:9. The options for <margins> are 0=margins disabled, or 1=margins enabled. The options for <interlace> are 0=progressive, or 1=interlaced. The options for <rb> are 0=normal, or 1=reduced blanking.

While still in the config.txt file, find the following lines, uncomment them if needed (delete the # mark in font of the line to uncomment it), and change them as shown:

hdmi_group=2 indicates using DMT (Display Monitor Timings), which is the standard typically used by monitors. hdmi_mode=87 indicates using the custom CVT mode that was added above. hdmi_drive=2 selects the Normal HDMI mode.

If you aren't sure what HDMI settings that you want to use, try this trick. First make sure the HDMI lines above are all commented out first. Power down the Raspberry Pi, connect the HDMI display that you want to use to the Raspberry Pi, and then power-up the Raspberry Pi. At start-up the HDMI settings will be negotiated. After start-up, open a terminal window, and enter:

This will provide the current HDMI settings. If these settings look good to you, then add them to the hdmi_cvt command above.

Auto-Starting a Script

For many hobby projects it is desirable to have the Raspberry Pi automatically start doing something when power is applied, without having to interact with it. Perform the following steps in order have the Raspberry Pi auto-execute a bash script on startup.

Open a terminal window, and enter

This will create a new empty file. In that file, enter the following items, save the file, and exit.

In the terminal window, enter the following:

This will return to the /home/pi directory, and create a new empty file. In that file, enter the following items, save the file, and exit.

At this point, this will only open an xterm window at startup. Later, this xterm window will be used to auto-launch the Python script by adding to the end of the xterm line, as an example: -e "sudo python ./datalogger/datalogger.py". The -e command tells the xterm window to execute the text provided in the double-quotes. The sudo is required if the python code is going to be accessing low-level hardware like I2C.

In the terminal window, enter the following to make the startup script executable:

If you list the contents of the directory using ls, the startup.sh script will be highlighted green to show that it is now executable.

To test whether the auto-exec scrpt is working, type "sudo reboot" in a command-line window. When the Raspberry Pi powers back up, there should be an xterm window in the center of the display, like this:

Save the "Project-Ready" Image

Now that you have gone through all of the work to make your Raspberry Pi "Project-Ready", it is highly recommended that you use the win32diskimager to save your image. This way, when you start a new project, or make an unrecoverable mistake during a project, you can easily start again from this point. Gracefully power down the Raspberry Pi by either selecting Shutdown from the desktop, or by typing "sudo init 0" in a command-line window.

After the Raspberry Pi powers down, unplug the Raspberry Pi, remove the SD card, place it into an SD card reader, and put the reader into an available USB port on the PC. Open the win32diskimager, select the blue folder icon to the right side of the Image File textbox, and browse to the location where you would like to save the new image. I recommend giving it a name such as "raspbian-wheezy-project-ready.img". Select the drive letter of the SD card that you want to read the image from. IMPORTANT: be very sure that you are selecting the correct drive letter. Once you are absolutely sure, select the Read button (NOT the Write button). This will begin reading from the SD card, and writing to the file on the PC. On my computer, reading from an 8GB card takes about 32 minutes.